This markdown is about making a simple MUSA 800 Practicum project on GitHub using Markdown and Rstudio. Requirements for this are a GitHub account, Git command line tool installed on your computer, Rstudio, and some knowledge of markdown and perhaps HTML. Aside from some preliminary setup, your work will be about editing an README.md document and, if you choose, committing you project work to GitHub. We will walk through all of these steps.
GitHub is a platform for code version control and collaboration. The Git in GitHub refers to a versioning protocol that allows a user or team to keep track of who changes what files, when and where. It is a very powerful protocol and GitHub harnesses that power into an easy to use cloud platform. Fortunately, GitHub makes a lot of the complex Git actions (e.g. Push, Pull, Commit, etc…) simple and intuitive. Combines with RStudio, the basics of Git version control are nearly as simple as pushing a button. Learning Git and GitHub is a skill that is very useful for controlling your own code and collaborating with others in this class and industry. Below are some links to help get familiar with what Git and GitHub have to offer.
The steps below cover the entire process for how to create a GitHub project accesible within RStudio.
Tools -> Global Options -> Git/SVNREADME.md to reflect a portfolio landing pageREADME.md up to data with your project pin-upsGo to https://github.com/
A program called Git is the underlying technology that allows for Rstudio and GitHub to communicate and perform version control. Git is considered a protocol as it defines how other programs communicate version control. Before Rstudio will work with version control, you need to install Git on your computer. You can visit the Git website and also check out Using Git with RStudio for some helpful instructions. It is usually a pretty easy install and you will want to accept the default settings most likely. Note that the Git protocol is very powerful and has many more features than the simple use case here.
There is a final setup step required to let Rstudio know that you have installed Git and where to look for it. In Rstudio click Tools -> Global Options -> Git/SVN. The check box for “Enable version control interface for Rstudio projects” should be checked and the box for “Git executable” should be the location in which in installed Git in the previous step.
Rstudio Git Settings
The term “fork” means to copy a GitHub code repository (aka “repo”) to your account. Your new repo and the original will be linked, but they will not update to each other unless specifically told to do so via a “pull request”. Forking the MUSA 800 Practicum Template. This action will duplicate the template repository to your GutHub account. The “fork” button is in the upper-right hand corner of the original repo.
Fork_repo
You can interact with your GitHub account in a number of ways, but we will use Rstudio as the means for editing and managing out portfolio. To setup Rstudio to do so, you need to create a New Project
new_project
Rstudio has a few different project formats, but you will pick the Version Control project to let Rstudio know you want to create a project from a GitHub repo.
version_control
There are two options for version controlled Rstudio projects, but we will chose Git.
version_control2
Cut/Paste the URL to your version of the portfolio repo into the “Repository URL”, the project name will populate as username. Finally, choose a directory to store your repo/files/code and make sure it is easy enough to navigate to; you will go there a bunch. Once you hit Create Project, Rstudio will go to that URL and copy all of the code to your hard drive; this is called cloning a repo.
git_clone
If everything went well, you will have a Git tab on your “Environments, History, etc…” tab in Rstudio (mine is lower-left, but yours may not be).
git_tab
Commit!The two main git operations we will use are commit and push. Commit means to save changes in files to a special git database on your local hard drive. The the push command communicates these changes with GitHub, lets you know if all the files sync up, and if all is clear it uploads the changed files. This is how the version control aspect of GitHub work.
Open the README.md from your repo/project in Rstudio and start making some changes. This file is written in markdown and will be the landing page for your project repo from the GitHub point of view. Use the same types of markdown syntax as you do with Rmarkdown, but note that R code blocks will not be evaluated in a basic *.md document.
README edit
Once you make some edits, go to the Git tab in Rstudio and you will see the names of the files that have changed. Click on the Commit button to stage your changes to be pushed to the GitHub. The image below is the staging area where you will need to click on the check-box next to each file that you want to commit the changes from. On the upper-right is a place to write a commit message. Make use of this space to write detailed messages. Click the Commit button.
git_commit
Once committed, click the Push button to send it to the server. You will likely have to type in your GitHub username and password each time you push code. I status message will appear and hopefully everything goes well!
git_push
If all went well in step 7, you should be able to go to your GitHub repo and see the new changes to the README after you refresh your browser. The README will be a living progress report for your project. Remeber, that this is a live repo, so do not put any sensitive data or material in this space!
README on GitHub
Continue to iterate the above steps and add to your project README as you move through the stages of your project.